What is Dialog Box Help Editor?

Dialog Box Help Editor is a program that you can use to create context-sensitive Help for programs that were designed for Windows 95 and later. Dialog Box Help Editor works closely with Microsoft Word, so make sure you've installed Microsoft Word for Windows 95 or later.

To use Dialog Box Help Editor, you need to provide only the name and location of the executable, .rc, or .res file that contains your dialog templates and the name and location of the .rtf file that contains your Help topics. If you don't already have an .rtf file, Dialog Box Help Editor can create one for you.

To create context-sensitive Help, all you need to do is choose which dialog box you want to write Help for, click a control in that dialog box, and then write. Afterward, you can use Dialog Box Help Editor to see what the context-sensitive Help will look like to users.

As you work, Dialog Box Help Editor assigns a unique ID to each control and creates an array that you can give your developer. Developers use the array to implement context-sensitive Help in their code.

Dialog Box Help Editor makes writing Help easier. But you can also use it to annotate the controls in a dialog box and to gather useful information, such as whether any of the controls in a dialog box have changed. For information about all of the tasks you can carry out using Dialog Box Help Editor, click the Help Topics button above.


Creating a new context-sensitive Help project
To create a new context-sensitive Help project

1	In Dialog Box Help Editor, click the File menu, and then click New Project.

2	In the Resource File box, specify the name and location of the file whose dialog boxes you want to write Help for. It is recommended that you use an executable file (for example, an .exe or .dll). You can also specify a .res or .rc file; however, if you specify an .rc file that includes header files, all those header files must be present in the location that is specified in the .rc file.

3	If you want to use a header file that contains constants, specify the file’s name and location in the Header File box.

4	In the Help Source area, specify the name of the .rtf file that contains your context-sensitive Help. If you want to create a new .rtf file, click New. Dialog Box Help Editor prompts you to name the file.

5	Click OK.

6	If you specified an .rc file in step 2, Dialog Box Help Editor prompts you to save it as a .res file. To accept the default file name, click Save.


A constant is an item that retains a constant value throughout the execution of a program, as opposed to a variable, whose value can change during execution. For example, the following is a constant:

#define IDC_CONTROL1	101


Assigning context-sensitive Help to the items in a dialog box
To assign context-sensitive Help to the items in a dialog box

1	In Dialog Box Help Editor, open the Dialog Box list, and then click the dialog box that you want to write context-sensitive Help for.

2	Click the control that you want to write Help for.

A colored box appears around the control. In your .rtf file, Dialog Box Help Editor inserts a pound sign (#) footnote and creates a topic for that control.

As you click new controls, a colored box appears around the controls that you have already clicked.

Important

Dialog Box Help Editor uses bookmarks to locate the topic that corresponds to a control. These bookmarks are located at the beginning of the red hidden text in each topic. Do not remove the bookmarks in your .rtf file. If you do, Dialog Box Help Editor will be unable to locate the topic.

Tips

Dialog Box Help Editor cannot create Help topics for controls whose ID is -1. These controls are usually identified by the IDC_STATIC constant. For information about writing context-sensitive Help for such a control, click Related Topics below.

The dialog box caption, control caption, and window class that are associated with a control appear in red hidden text in your .rtf file.

 Related Topics


Viewing the context-sensitive Help you've written
To view the context-sensitive Help you've written

1	In Dialog Box Help Editor, open the Dialog Box list, and then click the dialog box whose context-sensitive Help you want to view.

2	On the View menu, point to Context Help, and then click Compile & Test.

3	In the dialog box, click the  [image]  button, and then click the control whose Help you want to view. Or right-click the control, and then click the What’s This? command.

4	When you have finished viewing Help, click the View menu, point to Context Help, and then click Compile & Test again to clear the check mark.


Viewing the code that Dialog Box Help Editor generates
To view the code that Dialog Box Help Editor generates

1	In Dialog Box Help Editor, click the Options menu, and then click Preferences.

2	Click the Code tab, specify how you want Dialog Box Help Editor to display code, and then click OK.

3	Click the View menu, and then click Code.

Tips

The settings that you specify in the Preferences dialog box remain in effect until you change them. After you set them once, you can view code by clicking the View menu, and then clicking Code.

To restore the Dialog Box Help Editor window to its previous size, click the restore button in its title bar.

If you want to give a developer a header file that contains the code, click the File menu, click Save Code As, and then specify a name for the file.


Creating one array per dialog box
To create one array per dialog box

1	In Dialog Box Help Editor, click the Options menu, and then click Preferences.

2	On the Code tab, make sure that the Create One Array Per Dialog Box check box is selected.

Tip

To view the arrays, click the View menu, and then click Code.


An array is a collection of values that have a common name. In Dialog Box Help Editor, the values are pairs of control IDs and Help IDs.


Saving code as a header file
To save code as a header file

1	On the Options menu, click Preferences.

2	Click the Code tab, specify how you want Dialog Box Help Editor to display code, and then click OK.

3	On the View menu, click Code.

4	On the File menu, click Save Code As, and then specify a name for the header file.

Tip

The settings that you specify in the Preferences dialog box remain in effect until you change them. After you set them once, you can view code by clicking the View menu, and then clicking Code.


Determining whether any controls in a dialog box have changed
To determine whether any controls in a dialog box have changed

1	Make sure that all your source files are current.

2	In Dialog Box Help Editor, open the Dialog Box list, and then click the dialog box that you want to check for changes. If anything in the dialog box has changed, Dialog Box Help Editor displays a message.

3	Click the View menu, and then click Changes.

If a control caption, dialog box caption, dialog box ID, control ID, or control position has changed, or if a control has been deleted or added, a blue box appears around the item, and information about the change appears in the Dialog Box Help Editor window.

4	When you have finished viewing changes, click the View menu, and then click Changes to clear the check mark.

Tip

To restore the Dialog Box Help Editor window to its previous size, click the restore button in its title bar.


Keeping the dialog box you're writing Help for in the foreground
To keep the dialog box you're writing Help for in the foreground

In Dialog Box Help Editor, click the View menu, and then make sure Dialog On Top is selected.


Changing the source files for a Dialog Box Help Editor project
To change the source files for a Dialog Box Help Editor project

1	In Dialog Box Help Editor, click the Edit menu, and then click Project.

2	Change settings as needed.


Assigning a single Help topic to multiple controls
To assign a single Help topic to multiple controls

1	In Dialog Box Help Editor, open the Dialog Box list, and then click the dialog box that contains a control whose Help topic you want to share with other controls.

2	Click the Options menu, and then click Start Associating.

3	One by one, click all the controls that you want to assign to a single shared Help topic.

If the control is in another dialog box, open the Dialog Box list, click the name of the dialog box, and then click the control.

4	When you have clicked all the controls that you want to assign to a shared Help topic, click the Options menu, and then click Stop Associating.

5	In Word, write the Help topic for all the controls you clicked.


Restoring a control's original Help ID
To restore a control's original Help ID

1	In the Dialog Box list, click the dialog box that contains the control whose ID you want to restore.

2	Right-click the control, and then click Reset.

Tip

You might want to reset the Help ID for a control if you assigned a custom ID to it, if you associated that control with another control, or if you disabled Help for it. Resetting a control causes Dialog Box Help Editor to use the original ID that it assigned.


Assigning a custom Help ID
To assign a custom Help ID

1	In the Dialog Box list, click the dialog box that contains the control you want to assign a custom ID to.

2	Right-click the control, and then click Custom Help ID.

3	In the Help ID box, type the ID for the control or select an ID from the list.

If you want to use the Help IDs in an existing header file, click Read Header, and then locate the file.

4	In the Value box, type a numeric value. You assign a numeric value to ensure that a Help ID is unique. Therefore, don't use a number that you've used before.


Disabling Help for a control
To disable Help for a control

1	In the Dialog Box list, click the dialog box that contains the control whose Help you want to disable.

2	Right-click the control, and then click Disable Help.

Tips

You might want to disable Help for the explanatory text and decorative graphics in dialog boxes. This prevents an error message from appearing if users attempt to get context-sensitive Help for those items. If you don’t disable Help for a control that has no Help, the message "No Help topic is associated with this item" appears when users try to get Help for it.

If you change your mind and want to re-enable a control, right-click it, and then click Reset.


Annotating a control
To annotate a control

1	In the Dialog Box list, click the dialog box that contains the control you want to annotate.

2	Right-click the control, and then click Annotate.

3	Write your annotation, and then click OK

Tip

To view an annotation for a control, right-click it, and then click Annotate.


Viewing the properties of a control
To view the properties of a control

1	In the Dialog Box list, click the dialog box that contains the control whose properties you want to view.

2	Right-click the control, and then click Properties.


Questions and answers

The What's This? menu appears when I right-click a control. I want the context menu to appear instead.

The dialog box I'm writing Help for obscures the other windows I’m working in. How do I keep it from obscuring my work?

I want to assign Help to a label, but I receive a message that says no topic will be created.

I want to save code, but I can't.

I reset the Help ID on a control, but now when I click it, it jumps to the wrong topic in Word.


Ensuring that Dialog Box Help Editor locates the correct topic
To make sure that Dialog Box Help Editor can locate the correct topic in Word

1	Right-click the control that jumps to the wrong topic in Word, and then click Properties.

2	In the Topic ID area, write down the ID for the control, and then click OK.

3	In Word, click the Edit menu, and then click Bookmark.

4	In the Bookmark Name list, locate the ID that you identified in step 2.

5	Select the ID, and then click Delete.

The next time you click the control, Dialog Box Help Editor will create a new topic for that control.

Note

This problem can occur when you move or delete a topic in your .rtf file. When moving a topic, be sure to include the page break before the topic.


Displaying the context menu instead of the What's This? menu
To display the context menu instead of the What's This? menu

In Dialog Box Help Editor, click the View menu, point to Context Help, and then click Compile & Test to clear the check mark.


Preventing dialog boxes from appearing on top
To prevent dialog boxes from appearing on top

In Dialog Box Help Editor, click the View menu, and then click Dialog On Top to clear the check mark.


Assigning Help to a label whose ID is -1
To assign Help to a label whose ID is -1

1	If you receive an error message that says "The ID for this control is -1. No topic will be created," context-sensitive Help may work anyway. Write Help for the control that is associated with the label. Then display the dialog box in Dialog Box Help Editor, click the View menu, point to Context Help, and click Compile & Test. Check to see if context-sensitive Help works for the item. If it doesn't, try the following.

2	If no context-sensitive Help appears, ask your developer to rearrange the tabbing order of the controls in the resource script (.rc file). The label needs to precede the control that it is associated with. After the developer has reordered the controls, check to see if context-sensitive Help for the control works. If it doesn't, try the following.

3	Ask the developer to assign a valid ID (not -1 or IDC_STATIC) to the control so that you can assign Help to it.


Notes for developers

Dialog Box Help Editor builds an array of IDs and disables Help on appropriate controls when it builds the array. Dialog Box Help Editor cannot create Help topics for controls whose ID is -1. These controls are usually identified by the IDC_STATIC constant. To enable a Help author to write context-sensitive Help for such a control, change the tabbing order of the controls in the .rc file. For example, a label must precede the control that goes with it. Or assign a valid ID to the control.

Dialog Box Help Editor generates an array of control and Help IDs for each dialog box. Your Help author can provide you with this array to ensure that all controls are associated with unique Help IDs.


Closing a dialog box in Dialog Box Help Editor
To close a dialog box in Dialog Box Help Editor

Click anywhere in the dialog box, and then press ESC.


Specifying what type of Help IDs you want to use
To specify what type of Help IDs you want to use

1	In Dialog Box Help Editor, click the Options menu, and then click Preferences.

2	In the What Do You Want To Use As Help IDs area, specify what type of Help IDs you want to use.

3	If you want to use a default prefix other than IDH for all your IDs, specify that prefix in the Use The Following Prefix For Help IDs text box.


Using a prefix other than IDH for Help IDs
To use a prefix other than IDH for Help IDs

1	In Dialog Box Help Editor, click the Options menu, and then click Preferences.

2	In the Use The Following Prefix For Help IDs text box, type the prefix that you want to use.


Changing the color of the boxes Dialog Box Help Editor draws
To change the color of the boxes Dialog Box Help Editor draws

1	In Dialog Box Help Editor, click the Options menu, and then click Preferences.

2	Click the Color tab, and then click the Change button beside the item whose color you want to change.

3	Click a color, and then click OK.


Specifying a Word template for your RTF files
To specify a Word template for your .rtf files

1	In Dialog Box Help Editor, click the Options menu, and then click Preferences.

2	Click the Microsoft Word tab, and then click Browse.

3	Locate the template that you want to attach to your .rtf files, and then click Open.


Dialog Box Help Editor was brought
to you by:

Randy Feigner	Developer

Marcia Glover	Graphic designer

Petra Hoffmann	Writer

Susie Hunter	Editor

Tony Nahra	Editor

Laura Pinter	Indexer

Ralph Walden	Technical advisor

We extend our heartfelt thanks to those who offered suggestions and advice during the creation of this tool.


Provides a place to type the name and location of the file that contains the dialog boxes that you want to write context-sensitive Help for. It is recommended that you use an executable file, such as an .exe or a .dll. You can also use .res or .rc files, but if you specify an .rc file that includes header files, make sure that all the header files are in the location that the .rc file specifies.


Provides a place to type the name and location of a header file that contains control IDs. Although this is optional, it makes it easier for a developer to implement the context-sensitive Help that you write. Ask your developer whether a header file exists and, if so, what its location is.


Click this to locate the resource file that contains the dialog boxes you want to write context-sensitive Help for.


Click this to locate the header file that contains control IDs for the file specified in the Resource File box. Specifying a header file is optional.


Help is available for each item in this group. Click  [image]  at the top of the dialog box, and then click the item that you want information about.


Click this to locate the .rtf file that contains your context-sensitive Help topics. If you have not yet created an .rtf file, click New.


Provides a place to type the name and location of the .rtf file that contains your context-sensitive Help topics. If you have not yet created an .rtf file, click New.


Creates a new .rtf file in Microsoft Word and prompts you to specify a name and location for that file.


Provides a place to specify an ID if you don't want Dialog Box Help Editor to create one for you. If you have existing Help that you want to use for a newer version of a program, click the Read Header button, specify the name and location of your existing header file, and then choose the ID of the topic whose Help you want to update.


Click this to specify the location of an existing header file whose IDs you want to use.


Provides a place to type or change the numeric (map) value for the ID that is specified in the Help ID box. The value that you type must be unique.


Clears the entries in the Help ID and Value boxes.


Provides a place for you to type a note about the selected control.


Displays the text that appears in the title bar of the dialog box.


Displays the numeric value that identifies the dialog box in the source code.


Displays the text that appears on the control.


Displays the numeric value that identifies the control in the source code.


Displays the window class for the control. This describes what type of control it is.


Displays the Help topic ID that is currently assigned to the control. This ID may have been assigned by you or by Dialog Box Help Editor.


Displays the numeric (map) value that is associated with the Help topic ID.


Displays the time and date when you last interacted with the dialog box.


Displays the page number on which this Help topic appears in your .rtf file.


Indicates that Dialog Box Help Editor has added the control to the list of controls that it tracks.


Indicates that you have clicked the control.


Indicates that a control has changed. To view information about the changes, click the View menu, and then click Changes.


Indicates that a control, such as an OK or Cancel button, is associated with a default Help topic. Default Help topics are located in the Windows.hlp file, which is included with Windows 95 and later.


Displays the selected item in the list below and enables you to select and copy that item.


Lists all the controls that are associated with the Help topic that is specified in the Topic ID box.


Assigns IDs generated by Dialog Box Help Editor to your Help topics. Unless your developer requests otherwise, it is recommended that you use this setting.


Assigns IDs to your Help topics that are the same as the IDs for the controls that you're writing Help for. This option is easier on developers because they don't have to integrate a separate set of Help IDs into their code. They can simply use the control ID as the ID for both the control and its Help.


Assigns a Help ID that a developer has already assigned in code to your Help topic. Dialog Box Help Editor extracts this ID from your resource file.


If this box is checked, Dialog Box Help Editor organizes the code that it generates by dialog box.


Specifies which prefix Dialog Box Help Editor uses when assigning IDs to Help topics. If you specify a prefix other than IDH, open your project file in Help Workshop. Then click the Map button, and specify the prefix in the Instead Of IDH, Check These Prefixes box.


Displays code only for the controls that you clicked. If you wrote Help for each control after you clicked it, this option enables you to display and save code for only those controls that have Help. It also prevents errors from occurring when you compile your Help file.


Displays code for all the controls in the dialog boxes that you opened, even if you haven't clicked or written Help for those controls. If you choose this option, any controls that don't have Help will generate errors when you compile your Help file.


Includes both Help IDs and arrays in the code that Dialog Box Help Editor generates. Choose this option if you want to view all of the code that Dialog Box Help Editor generates at once, or save it all in one file. If you're generating a header file that you intend to include in the Map section of your project (.hpj) file, choose the Help IDs Only option instead.


Includes only Help IDs in the code that Dialog Box Help Editor generates. Choose this option if you're generating a header file that you intend to include in the Map section of your project (.hpj) file.


Includes only arrays in the code that Dialog Box Help Editor generates. Choose this option if your developer requests only arrays in the code that you provide.


Indicates what color Dialog Box Help Editor uses to show which control you clicked most recently. To change the color, click Change.


Indicates what color Dialog Box Help Editor uses to show which controls you clicked. Dialog Box Help Editor adds a topic for each of these controls to your .rtf file. To change the color, click Change.


Indicates what color Dialog Box Help Editor uses to show which controls in your resource file have changed. To change the color, click Change. For more information about a control that has changed, click the View menu, and then click Changes.


After you click Start Associating on the Options menu, Dialog Box Help Editor draws boxes of this color around the controls that share a single Help topic. When you click Stop Associating, the color specified in the Controls That I Clicked box replaces this color. To change this color, click Change.


Click this to change the color that Dialog Box Help Editor uses for this control.


Specifies the location and name of the template that Dialog Box Help Editor attaches to your .rtf files.


Click this to specify the location and name of the template that you want Dialog Box Help Editor to attach to your .rtf files.